/*
 * 
 * Copyright  1990-2009 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package javax.microedition.media.control;

/**
 * The <code>FramePositioningControl</code> is the interface to control 
 * precise positioning to a video frame for <code>Players</code>.
 * <p>
 * Frame numbers for a bounded movie must be non-negative 
 * and should generally begin with 0,
 * corresponding to media time 0.  Each video frame of a movie
 * must have a unique frame number that is one bigger than the
 * previous frame. 
 * <p>
 * There is a direct mapping between the frame number and the media
 * time of a video frame; although not all <code>Players</code> can
 * compute that relationship.  For <code>Players</code> that can
 * compute that relationship, the <code>mapFrameToTime</code> and
 * <code>mapTimeToFrame</code> methods can be used.
 * <p>
 * When a <code>Player</code> is seeked or skipped to a new video frame, 
 * the media time of the <code>Player</code> will be changed to the 
 * media time of the corresponding video frame.
 * <p>
 * As much as possible, the methods in this interface should 
 * provide frame-level accuracy with a plus-or-minus-one-frame 
 * margin of error to accommodate for round-off errors.  
 * However, if the content has inaccurate frame positioning 
 * information, implementations may not be able to provide
 * the necessary frame-level accuracy.  For instance, some
 * media content may contain wrong time-stamps or have missing 
 * frames.  In any case, the results of each
 * operation should represent the best effort.  For the
 * <code>seek</code> and <code>skip</code> methods, the returned 
 * value should indicate the actual new location or the number
 * of frames skipped.
 *
 */
public interface FramePositioningControl extends javax.microedition.media.Control {

    /**
     * Seek to a given video frame.
     * The media time of the <code>Player</code> will be updated 
     * to reflect the new position set.
     * <p>
     * This method can be called on a stopped or started 
     * <code>Player</code>.
     * If the <code>Player</code> is
     * in the <i>Started</i> state, this method may cause the
     * <code>Player</code> to change states.  If that happens, the
     * appropriate transition events will be posted by
     * the <code>Player</code> when its state changes.
     * <p>
     * If the given frame number is less than the first or larger
     * than the last frame number in the media, <code>seek</code>
     * will jump to either the first or the last frame respectively.
     *
     * @param frameNumber the frame to seek to.
     * @return the actual frame that the Player has seeked to. 
     */
    int seek(int frameNumber);

    /**
     * Skip a given number of frames from the current position.
     * The media time of the <code>Player</code> will be updated to 
     * reflect the new position set.
     * <p>
     * This method can be called on a stopped or started <code>Player</code>.
     * If the <code>Player</code> is in the <i>Started</i> state,
     * the current position is changing.  Hence, 
     * the frame actually skipped to will not be exact.
     * <p>
     * If the <code>Player</code> is
     * in the <i>Started</i> state, this method may cause the
     * <code>Player</code> to change states.  If that happens, the
     * appropriate transition events will be posted.
     * <p>
     * If the given <code>framesToSkip</code> will cause the position to
     * extend beyond the first or last frame, <code>skip</code> will
     * jump to the first or last frame respectively.
     *
     * @param framesToSkip the number of frames to skip from the current
     *   position.  If framesToSkip is positive, it will seek forward
     *   by framesToSkip number of frames.  If framesToSkip is negative, 
     *   it will seek backward by framesToSkip number of frames.
     *   e.g. skip(-1) will seek backward one frame.
     * @return the actual number of frames skipped.  
     */
    int skip(int framesToSkip);

    /**
     * Converts the given frame number to the corresponding media time.
     * The method only performs the calculations.  It does not
     * position the media to the given frame.
     * 
     * @param frameNumber the input frame number for the conversion.
     * @return the converted media time in microseconds for the given frame.  
     * If the conversion fails, -1 is returned.
     */
    long mapFrameToTime(int frameNumber);

    /**
     * Converts the given media time to the corresponding frame number.
     * The method only performs the calculations.  It does not
     * position the media to the given media time.
     * <p>
     * The frame returned is the nearest frame that has a media time
     * less than or equal to the given media time.
     * <p> 
     * <code>mapTimeToFrame(0)</code> must not fail and must 
     * return the frame number of the first frame. 
     * 
     * @param mediaTime the input media time for the 
     * conversion in microseconds.
     * @return the converted frame number for the given media time.  
     * If the conversion fails, -1 is returned.
     */
    int mapTimeToFrame(long mediaTime);
}


